//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: PersistentTypeSelector.cs
//
//  Description: Delegate invoked each time before object is created.
// 
//--------------------------------------------------------------------------

using System;

namespace Chili.Opf3
{
	/// <summary>
	/// Allows to specify a method that is invoked each time before a persistent object is created.
	/// </summary>
	/// <remarks>
	/// <para>
	/// This delegate allows to specify a method that is invoked each time before a persistent object is created.
	/// The type of the persistent object to create may be changed or the current row (item) in the storage may be 
	/// ignored by applying the Ignore property of the <see cref="FetchingStorageRecordEventArgs">FetchingStorageRecordEventArgs</see> 
	/// class.
	/// </para>
	/// <para>
	/// This delegate is very useful in inheritance chains. It allows you to specify an inherited type as type of
	/// the persistent object, by analyzing the fields of the current row (item) of the storage or by having some
	/// other algorithm that decides how which type of class to create.
	/// </para>
	/// </remarks>
	/// <example>
	/// The following sample shows the usage of this delegate in some methods of the 
	/// <see cref="ObjectContext">ObjectContext</see>.
	/// <code lang="CS">
	/// // Creates a new ObjectContext that uses an MsSql Server as storage.
	/// ObjectContext context = new ObjectContext(new MsSqlStorage("sa", "", "localhost", "application"));
	///  
	/// // ... Other code.
	///  
	/// // Get the ObjectSet with user matching the name and sorting them by name.
	/// ObjectSet&lt;User&gt; objectSet = context.GetObjectSet&lt;User&gt;(new PersistentTypeSelector(MySelection));
	///  
	/// // Loop through all items and do something.
	/// foreach(User user in objectSet)
	/// {
	///     // Do something.
	/// }
	/// 
	/// // ...
	/// 
	/// private void MySelection(object sender, FetchingStorageRecordEventArgs e)
	/// {
	///     if (e.DataRecord["Type"] == "1")
	///     {
	///         // Switch the type of the persistent that is created to User1.
	///	        e.Type = typeof(User1);
	///     }
	///     else if ((bool)e.DataRecord["Ignore"])
	///     {
	///         // Tell the framework to ignore this item.
	///         e.Ignore = true;
	///     }
	///		else
	///		{
	///			// Have a persistent of type User created.
	///			e.Type = typeof(User);
	///		}
	/// }
	/// </code>
	/// </example>
	/// <param name="sender">The object who invoked the delegate.</param>
	/// <param name="e">An instance of the <see cref="FetchingStorageRecordEventArgs">FetchingStorageRecordEventArgs</see>
	/// class containing all necessary properties to change the type or have the current item ignored.</param>
	public delegate void PersistentTypeSelector(object sender, FetchingStorageRecordEventArgs e);
}
